Add Material Support to Globe #5919

jasonbeverage · 2017-10-20T19:01:51Z

Hi all!

This PR adds Material support to the Globe, as well as adding new height and slope values to the czm_materialInput struct so that it can be used as input when generating the materials.

I've added a new sandcastle example that you can play with here

The main goal of this effort was to visualize changes in slope on the terrain, but I tried to make it more generic by utilizing the existing Material support so we could do some more interesting effects in the future. I've added some new materials that you can see in use in the sandcastle example

ElevationContour - Displays elevation contour lines on the terrain with the spacing controled via a uniform. You can drag the slider in the sandcastle example to change the spacing.
ElevationRamp - Colors the terrain by applying a color ramp to the elevation. The elevation is scaled between minHeight and maxHeight uniforms and then does a texture lookup into the ramp to get the color. This ended up being really cool because you can generate nice color ramps programatically using a canvas and the createLinearGradient function.
SlopeRamp - Colors the terrain by applying a color ramp to the slope.

Some notes on the implementation:

I tried to keep the changes as minimal as possible and just re-use the great work already done in the existing Material framework.
The Globe now has a new material property which you can set to any Material you like.
Globe has a new dirtyShaders function that is called when you change the material so the correct material shader is injected in the globe shader.
If there is no material there shouldn't be a performance penalty b/c it's wrapped in a APPLY_MATERIAL define which is only set if there is material present.
GlobeSurfaceShader has a new material property so it can detect when the material has changed and a new shader needs to be generated.
GlobeSurfaceTileProvider has a new uniformMap property that is set to the materials uniforms so they are incorporated in the tile draw calls.
Currently the material only effects the diffuse color of the terrain. The original imagery color is blended with the materials color based on the materials alpha. This allows you to return an alpha value less than 1 to get the original imagery color to blend though. For example, try changing one of the color stops in the color ramp to "transparent" or "rgba(255,0,0,0.5)" and see the imagery come through.

Thanks!

Jason

…now uses a color ramp image

Properties.html

pjcozzi · 2017-10-21T19:33:42Z

@jasonbeverage this is super exciting, thanks again!

Here's Seneca Rocks where I use to rock climb:

For the contours, consider adding an optional where they "maintain" constant pixel width using screen-space partial derivatives. Perhaps something like this: https://github.com/AnalyticalGraphicsInc/cesium/blob/a81f2e7de64c2348558046b5e8e685278fde0dcf/Source/Shaders/Materials/GridMaterial.glsl#L23

@lilleyse can you take a first pass at this? I would like to do a quick review before merging.

jasonbeverage · 2017-10-21T21:07:15Z

That's awesome you used to rock climb in Seneca Rocks! I'm from West Virginia so I've been there a bunch as a kid and I went camping and trout fishing in that area last year with my uncle.

…

On Sat, Oct 21, 2017 at 3:33 PM Patrick Cozzi ***@***.***> wrote: @jasonbeverage <https://github.com/jasonbeverage> this is super exciting, thanks again! Here's Seneca Rocks where I use to rock climb: [image: image] <https://user-images.githubusercontent.com/782098/31855226-f10226ae-b674-11e7-8435-a9bb865763ad.png> For the contours, consider adding an optional where they "maintain" constant pixel width using screen-space partial derivatives. Perhaps something like this: https://github.com/AnalyticalGraphicsInc/cesium/blob/a81f2e7de64c2348558046b5e8e685278fde0dcf/Source/Shaders/Materials/GridMaterial.glsl#L23 @lilleyse <https://github.com/lilleyse> can you take a first pass at this? I would like to do a quick review before merging. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#5919 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAT74nlgO05xAWOOYOt_uojSFergVoTnks5sukccgaJpZM4QBF3x> .

pasu · 2017-11-02T02:00:43Z

Hi, I also did this job but I just modified the globefs directly, I never thought adding material to support globe, it is a decent design, I gained it.

Here is my little suggestion to set the contour line.
Source/Shaders/Materials/ElevationContourMaterial.glsl:
czm_material material = czm_getDefaultMaterial(materialInput);

float dContourInterval = 100.0;// the interval value of contour line
float distanceToContour = mod(materialInput.height, dContourInterval);
float dxc = abs(dFdx(materialInput.height));
float dyc = abs(dFdy(materialInput.height));
float dF = max(dxc, dyc);
material.alpha = (distanceToContour < dF) ? 1.0 : 0.0;

material.diffuse = color.rgb;

return material;

lilleyse

This looks great so far! I have a few structural comments, but overall the approach is solid.

lilleyse · 2017-11-03T18:39:29Z

Apps/Sandcastle/gallery/Globe Materials.html

+});
+viewer.terrainProvider = cesiumTerrainProviderMeshes;
+
+viewer.scene.globe.enableLighting = true;


The demo works better without lighting. Related to my comment below, we should be able to get the normals properly without this being set.

The color ramps are better with lighting so you can see the terrain features. The terrain all blends together without the shadows.

The lighting does look fine most of the time, it's mainly when it's completely dark that it's hard to see what's going on.

I disagree. For example, there are some random Appalachian mountains with and without lighting:

Having the lighting enabled makes a big difference.
To make sure the lighting always looks good with the preset views, we can add a line to set the clock time:
viewer.clockViewModel.currentTime = Cesium.JulianDate.fromDate(new Date(2017, 8, 22, 0, 0, 0));

Ok yeah, setting the clock is good. I should have been clearer, my main issue was that whenever I would open the demo it would be night at Everest and just hard to see anything.

I've pushed a change to set the clock time.

lilleyse · 2017-11-03T18:50:55Z

Apps/Sandcastle/gallery/Globe Materials.html

+        viewer.scene.globe.material.uniforms.color = Cesium.Color.RED;
+    }
+}, {
+    text : 'Slope Color Ramp Material',


This material doesn't work with enableLighting off.

If the material requires normals you can pass in the define GENERATE_POSITION_AND_NORMAL to the globe vertex shader.

For terrain that doesn't contain normals the material should be ignored so it doesn't appear black.

lilleyse · 2017-11-03T19:13:13Z

Source/Scene/Globe.js

@@ -525,6 +540,10 @@ define([
            return;
        }

+        if (this._material) {


Use defined(this._material).

lilleyse · 2017-11-03T19:13:25Z

Source/Scene/Globe.js

+
+        var fragmentSources = [];
+        var fragmentDefines = [];
+        if (this._material) {


Same comment.

lilleyse · 2017-11-03T19:28:08Z

Source/Scene/Globe.js

+            fragmentDefines.push('APPLY_MATERIAL');
+
+            // Set the material uniform map to the materials
+            this._surface._tileProvider.uniformMap = this._material._uniforms;


uniformMap should be defined in the constructor of GlobeSurfaceTileProvider.

Also a better name would be materialUniformMap.

lilleyse · 2017-11-03T20:21:01Z

Source/Scene/GlobeSurfaceTileProvider.js

@@ -1262,6 +1264,10 @@ define([
            uniformMapProperties.minMaxHeight.y = encoding.maximumHeight;
            Matrix4.clone(encoding.matrix, uniformMapProperties.scaleAndBias);

+            if (tileProvider.uniformMap) {
+                 uniformMap = combine(uniformMap, tileProvider.uniformMap);
+            }


It would be best to combine uniforms elsewhere since this will allocate a uniform map object every frame.

I wonder if this could be moved to the area near if (tileProvider._drawCommands.length <= tileProvider._usedDrawCommands) {. Can it detect when the material is dirty and combine up there?

lilleyse · 2017-11-03T20:24:41Z

Source/Shaders/GlobeVS.glsl

@@ -21,6 +21,8 @@ varying vec3 v_positionEC;
 varying vec3 v_textureCoordinates;
 varying vec3 v_normalMC;
 varying vec3 v_normalEC;
+varying float v_slope;


Everything in here should also be surrounded by the APPLY_MATERIAL define too.

lilleyse · 2017-11-03T20:27:09Z

Source/Shaders/GlobeFS.glsl

@@ -61,6 +61,8 @@ varying vec3 v_positionEC;
 varying vec3 v_textureCoordinates;
 varying vec3 v_normalMC;
 varying vec3 v_normalEC;
+varying float v_height;
+varying float v_slope;


Surround these with the APPLY_MATERIAL define.

lilleyse · 2017-11-03T20:30:45Z

Source/Scene/GlobeSurfaceTileProvider.js

@@ -1262,6 +1264,10 @@ define([
            uniformMapProperties.minMaxHeight.y = encoding.maximumHeight;
            Matrix4.clone(encoding.matrix, uniformMapProperties.scaleAndBias);

+            if (tileProvider.uniformMap) {


Use defined.

lilleyse · 2017-11-03T20:37:17Z

Added some style tweaks in 60c0121

lilleyse · 2017-11-03T20:39:38Z

Remaining TODO:

Tests
Improve contour lines: Add Material Support to Globe #5919

hpinkos · 2017-11-08T21:41:47Z

Source/Scene/Material.js

+            uniforms : {
+                image: Material.DefaultImageId,
+                minHeight: 0.0,
+                maxHeight: 10000.0,


Change these to minimumHeight and maximumHeight. We try to avoid abbreviations so there's no confusion

Remove the dangling comma here

pjcozzi · 2017-11-12T19:46:59Z

@jasonbeverage are you able to make the suggested changes to get this over the finish line for the upcoming 1.40 release? 😄

jasonbeverage · 2017-11-13T15:04:08Z

Hey Patrick I'll work on getting these addressed real soon. Thanks!

…

On Sun, Nov 12, 2017 at 2:47 PM Patrick Cozzi ***@***.***> wrote: @jasonbeverage <https://github.com/jasonbeverage> are you able to make the suggested changes to get this over the finish line for the upcoming 1.40 release? 😄 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#5919 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAT74r4tBfgThaLw3cZ2fjTJIXJTc3kxks5s10s5gaJpZM4QBF3x> .

pjcozzi · 2017-11-13T15:11:30Z

Very nice, rock on @jasonbeverage!

…cent on first view of Mt Everest

…onRampMaterial

Added implementation of screen space partial derivatives for contour lines to make them look nicer. Source/Shaders/Materials/ElevationContourMaterial.glsl

jasonbeverage · 2017-11-13T19:43:43Z

I just pushed a change to the ElevationContourMaterial that uses the code from @pasu to implement the screen space partial derivative based contouring. I also added a new lineThickness uniform so you can control the thickness of the line. It looks pretty good to me.

I think my recent changes addresses everything mentioned here. Let me know if you see anything else!

pjcozzi

@jasonbeverage this is good stuff as always! We would like to include this in the 1.40 release going out on Friday so we would like to get this into master ASAP.

Do you have time to
(1) make the mostly trivial changes I requested?
(2) add unit tests?

Thanks!!!

pjcozzi · 2017-11-24T18:14:35Z

CHANGES.md

@@ -3,6 +3,7 @@ Change Log

 ### 1.40 - 2017-12-01

+* Adds Material support to Globe. [#5919](https://github.com/AnalyticalGraphicsInc/cesium/pull/5919)


Can this link to the future Sandcastle example that will live here: https://cesiumjs.org/Cesium/Apps/Sandcastle/

pjcozzi · 2017-11-24T18:17:31Z

Apps/Sandcastle/gallery/Globe Materials.html

+    ramp.height = 1;
+    var ctx = ramp.getContext('2d');
+
+    var values = selectedShading === 'elevation' ? elevationRamp : slopeRamp;


@hpinkos can the color ramp be tweaked to be a bit less subtle for the default view?

Or change the default view.

I changed the default view to be of the Himalayas

pjcozzi · 2017-11-24T18:20:08Z

Source/Scene/Globe.js

+    /**
+     * @private
+     */
+    Globe.prototype.dirtyShaders = function() {


We would generally name this a verb like makeShadersDirty and not make it on the Globe object; instead, it would be a stand-alone function at file level scope and then we pass in a Globe object. This provides better encapsulation.

pjcozzi · 2017-11-24T18:21:57Z

Source/Scene/Globe.js

+            fragmentSources.push(this._material.shaderSource);
+            defines.push('APPLY_MATERIAL');
+
+            // Set the material uniform map to the materials


Probably don't need this comment.

pjcozzi · 2017-11-24T18:23:02Z

Source/Scene/Globe.js

+
+        this._surfaceShaderSet.baseVertexShaderSource = new ShaderSource({
+            sources : [GroundAtmosphere, GlobeVS],
+            defines: defines


Throughout, we would generally write defines : with a space before the semicolon. The auto formatter in your IDE probably does this. WebStorm does.

pjcozzi · 2017-11-24T18:24:11Z

Source/Scene/Material.js

+     *  <ul>
+     *      <li><code>color</code>: color and alpha for the contour line.</li>
+     *      <li><code>spacing</code>: spacing for contour lines in meters.</li>
+     *      <li><code>lineThickness</code>: Number specifying the thickness of the grid lines in pixels.</li>


To be consistent with the rest of the Cesium API, can this be "width" instead of "thickness?"

pjcozzi · 2017-11-24T18:25:30Z

Source/Shaders/Builtin/Structs/materialInput.glsl

@@ -10,6 +10,8 @@
 * @property {vec3} normalEC Unperturbed surface normal in eye coordinates.
 * @property {mat3} tangentToEyeMatrix Matrix for converting a tangent space normal to eye space.
 * @property {vec3} positionToEyeEC Vector from the fragment to the eye in eye coordinates.  The magnitude is the distance in meters from the fragment to the eye.
+ * @property {float} height The height of the terrain.  Only available for globe materials.


Can this be more explicit? I assume the height in meters above or below the WGS84 ellipsoid?

pjcozzi · 2017-11-24T18:25:57Z

Source/Shaders/Builtin/Structs/materialInput.glsl

@@ -10,6 +10,8 @@
 * @property {vec3} normalEC Unperturbed surface normal in eye coordinates.
 * @property {mat3} tangentToEyeMatrix Matrix for converting a tangent space normal to eye space.
 * @property {vec3} positionToEyeEC Vector from the fragment to the eye in eye coordinates.  The magnitude is the distance in meters from the fragment to the eye.
+ * @property {float} height The height of the terrain.  Only available for globe materials.
+ * @property {float} slope The slope of the terrain normalized from 0 to 1.  Only available for globe materials.


Can this be more explicit, e.g., 0 is flat and 1 is vertical or vice versa?

pjcozzi · 2017-11-24T18:30:18Z

Source/Shaders/GlobeVS.glsl

@@ -167,4 +172,11 @@ void main()
    v_rayleighColor = atmosColor.rayleigh;
    v_distance = length((czm_modelView3D * vec4(position3DWC, 1.0)).xyz);
 #endif
+
+#ifdef APPLY_MATERIAL
+    vec3 finalNormal = normalize(v_normalMC);


No need to normalize, it is already done: https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Source/Shaders/Builtin/Functions/octDecode.glsl#L24

pjcozzi · 2017-11-24T18:31:47Z

Source/Shaders/GlobeVS.glsl

+
+#ifdef APPLY_MATERIAL
+    vec3 finalNormal = normalize(v_normalMC);
+    vec3 worldNormal = normalize(v_positionMC.xyz);


Here and the line above, we generally try to treat varyings in a vertex shader as "write once, don't read" - more for style - I don't think it matters for performance.

Here, the return from czm_octDecode could be assigned to a local, and position3DWC can be used instead of v_positionMC.

Also worldNormal is a confusing name - since it is not the terrain normal in world coordinate - perhaps rename to ellipsoidNormal since this is normal to the ellipsoid?

jasonbeverage · 2017-11-24T22:42:24Z

Hey @pjcozzi I'll try to make those changes tonight or tomorrow. Do you have an example of something I could use for inspiration for the unit tests? I'm still not the best at writing them :)

I'm heading out of town for the IITSEC conference on Sunday and won't be back until the end of the week, so I'll try to get what I can wrapped up before I head out.

pjcozzi · 2017-11-25T13:49:40Z

@jasonbeverage awesome - it is deeply appreciated!

I'm not sure that it is the best example, but here is a simple example for rendering a globe in a unit test:

https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Specs/Scene/SceneSpec.js#L488-L505

For your unit tests, just cover rendering with each type of material and all the edge cases, e.g., changing material, going from no material to material, from material to no material, perhaps changing uniforms, etc.

The test guiding is pretty is good:

https://github.com/AnalyticalGraphicsInc/cesium/tree/master/Documentation/Contributors/TestingGuide#testing-guide

Also:

Please keep your eye out for cool Cesium apps at IITSEC - would love to hear what you find!
What is your next Cesium feature? 😄

…ction intead of a private function

jasonbeverage · 2017-11-25T19:13:57Z

I think I've addressed all of your comments except for the unit tests.

jasonbeverage · 2017-11-25T19:37:16Z

I just added a few unit tests that appear to pass :)

I'm heading out for the rest of the day and will be gone until next Wednesday but I'll be answering email and checking this PR if you need anything ;)

pjcozzi · 2017-11-25T19:52:57Z

Very nice, thanks again @jasonbeverage. Have a great conference!

jasonbeverage · 2017-11-25T22:16:47Z

Thanks for merging this! I'll hopefully have at least one more little PR before the end of the year :)

MapGiser · 2019-04-26T08:59:37Z

Hi, I also did this job but I just modified the globefs directly, I never thought adding material to support globe, it is a decent design, I gained it.
Here is my little suggestion to set the contour line.
Source/Shaders/Materials/ElevationContourMaterial.glsl:
czm_material material = czm_getDefaultMaterial(materialInput);
float dContourInterval = 100.0;// the interval value of contour line
float distanceToContour = mod(materialInput.height, dContourInterval);
float dxc = abs(dFdx(materialInput.height));
float dyc = abs(dFdy(materialInput.height));
float dF = max(dxc, dyc);
material.alpha = (distanceToContour < dF) ? 1.0 : 0.0;
material.diffuse = color.rgb;
return material;
I want to draw counterline in restrict area, can you give me some advise?thanks

Abhishek950650 · 2020-09-24T05:54:14Z

@jasonbeverage. Hello i am trying to implement Cesium globe materials slope, elevation, aspect features in my local project but i am facing issue in my project if i apply any these options my globe is not showing perfect output its look like only single color on my whole globe 🌐 like red or blue or green
How i resolve this issue..

Thanks

OmarShehata · 2020-09-24T14:07:15Z

@Abhishek950650 I would ask your question in the Cesium community forum (https://community.cesium.com/) so others can take a look and help out. Include more information like a Sandcastle and how you're using these materials (see https://community.cesium.com/t/how-to-share-custom-sandcastle-examples/9828)

jasonbeverage added 8 commits October 20, 2017 13:28

Added material support to the globe

24ff46b

Removed SlopeMaterial shader in favor of the SlopeRampMaterial which …

4e3ae37

…now uses a color ramp image

Got rid of multiple enableLighting calls

6c2d17c

Unsetting uniformMap if there is no material

ce71917

Updated CHANGES.md

a2152cc

Updated CHANGES.md with PR reference

5139bad

Fix eslint warning

29d4ae2

Merge remote-tracking branch 'upstream/master' into globematerials

11325f2

Properties.html

Merge branch 'master' into globematerials

9b7f7d9

lilleyse reviewed Nov 3, 2017

View reviewed changes

Style tweaks

60c0121

lilleyse added 2 commits November 3, 2017 16:37

Merge branch 'master' into globematerials

46d1a17

Merge branch 'master' into globematerials

3ba02db

hpinkos reviewed Nov 8, 2017

View reviewed changes

jasonbeverage added 6 commits November 13, 2017 10:29

Setting initial time in Globe Materials demo to make lighting look de…

cbcaea1

…cent on first view of Mt Everest

Using defined to check for material in Globe

cff763d

Using defined to check for uniformMap

5c619a9

Wrapping slope and height and globe shaders with APPLY_MATERIAL ifdef.

7493d7c

Renamed minHeight/maxHeight => minimumHeight/maximumHeight in Elevati…

5e4aab6

…onRampMaterial

Added lineThickness uniform to ElevationContourMaterial

c045a6c

Added implementation of screen space partial derivatives for contour lines to make them look nicer. Source/Shaders/Materials/ElevationContourMaterial.glsl

fancy sandcastle demo

8f4a8a1

pjcozzi requested changes Nov 24, 2017

View reviewed changes

jasonbeverage added 10 commits November 25, 2017 13:41

Changed link in CHANGES.md to Globe Material sandcastle demo

8ca9ac9

Changed dirtyShaders to makeShadersDirty and made it a file level fun…

0697c45

…ction intead of a private function

Remove comment

83dedf0

Formatting

a5fd43f

Renamed lineThickness to width for ElevationContourMaterial

e469dd7

Clarification of height in materialInput

560caa5

Commenting slope in materialInput

cc77f3a

Not normalizing v_normalMC in GlobeVS.glsl

8c30e90

Not reading varying values in GlobeVS

5bd104f

Changed default viewpoint of GlobeMaterials to the Himalayas

a71d73a

jasonbeverage added 2 commits November 25, 2017 14:31

Added unit tests for rendering a globe with materials

b42d079

Added sets material test for Globe

0264ab1

pjcozzi added 2 commits November 25, 2017 14:43

Tweak CHANGES.md

8eb3bd4

Whitespace

217ce3a

pjcozzi approved these changes Nov 25, 2017

View reviewed changes

Default Globe Material Sandcastle example to elevation shading

fc88b02

pjcozzi merged commit 7799186 into CesiumGS:master Nov 25, 2017

hpinkos mentioned this pull request Dec 4, 2017

FEATURE REQUEST: contour lines #5887

Closed

lilleyse mentioned this pull request Dec 8, 2017

Picking with Globe Materials / Globe Lighting enabled makes the shader compilation fail #6039

Closed

hpinkos mentioned this pull request Dec 13, 2018

Supply both slope and aspect to shader in radians #7409

Open

		@@ -3,6 +3,7 @@ Change Log

		### 1.40 - 2017-12-01

		* Adds Material support to Globe. [#5919](https://github.com/AnalyticalGraphicsInc/cesium/pull/5919)

Add Material Support to Globe #5919

Add Material Support to Globe #5919

Conversation

jasonbeverage commented Oct 20, 2017

pjcozzi commented Oct 21, 2017

jasonbeverage commented Oct 21, 2017 via email

pasu commented Nov 2, 2017

lilleyse left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lilleyse Nov 8, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lilleyse commented Nov 3, 2017

lilleyse commented Nov 3, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pjcozzi commented Nov 12, 2017

jasonbeverage commented Nov 13, 2017 via email

pjcozzi commented Nov 13, 2017

jasonbeverage commented Nov 13, 2017

pjcozzi left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasonbeverage commented Nov 24, 2017

pjcozzi commented Nov 25, 2017

jasonbeverage commented Nov 25, 2017

jasonbeverage commented Nov 25, 2017

pjcozzi commented Nov 25, 2017

jasonbeverage commented Nov 25, 2017

MapGiser commented Apr 26, 2019

Abhishek950650 commented Sep 24, 2020

OmarShehata commented Sep 24, 2020

lilleyse Nov 8, 2017 •

edited

Loading